3delite's Tags Library

^
^
^
^
^
^
^
^
^
^
^
^
^

^{Download ::

Top}

Tags Library

Tags Library is a tag reader-writer component for Delphi (Win32, Win64, OSX, iOS, Android and Linux)and Lazarus/Free pascal and a .dll for developer environments supporting usage of Win32, Win64 .dlls (C++, VB, C#, VB.NET etc.) or COM classes (eg. VBScript).
The component reads and writes all common audio file tag formats additionaly tags in MP4, WMV and Ogg Theora video files.
One of the advantages of using Tags Library is that it can convert the tags and cover arts between the supported tagging standards automatically. Just load the source file's tags and save it to the destination file, the appropriate tag format and tags (including cover arts) will be automatically converted.

Features:

Loading of ID3v1, ID3v2, Lyrics3, APEv1, APEv2, Flac (including Ogg Flac), Ogg Vorbis, Opus, MP4 (including video files and 64bit atom size files), WAV LIST INFO, BEXT and CART (including RF64 WAV files) and WMA tags
Saving of ID3v1, ID3v2, Lyrics3, APEv2, Flac (including Ogg Flac), Ogg Vorbis, Opus, MP4 (including video files and 64bit atom size files), WAV LIST INFO, BEXT and CART (including RF64 WAV files) and WMA tags
Removing of all the supported tags
Functions for reading/writing/removing tags for a file in memory
Built in support for extracting and inserting album cover pictures for all the supported tag formats
Handle the tags transparently or call direct functions for particular tags
Integration with BASS, load tags from BASS channel handles (local or URL streams)
Get source audio file's attributes (MPEG, AIFF/AIFC, Flac, Ogg Vorbis, Opus, WAV, MusePack, WavPack)
Fully unicode
Pure Delphi code, no external dependencies (except the WMA format, which is available only on Windows), Delphi XE2 64bit and OSX32, Delphi XE5 iOS and Android compatible
.dll version provided for Win32 and Win64 (.NET and COM wrapper .dll also included)

Download Tags Library

The used Delphi tagging units are also available separatelly:

If you have any question, please write to: 3delite@3delite.hu

Tags Library in shareware and commercial software?

The component comes with full source code (Delphi units) and can be evaluated freely. If you like it and decide to use it in a freeware, shareware or commercial (or any other money making - advertising, in app. selling, etc.) product one of the licenses is needed.

Installation

Add the directories to the tagging libraries ('..\Delphi\Tagging Libraries\APEv2 Library\' etc.) to the search path, and to Uses list add: TagsLibrary.

If you install the library with the setup.exe the COM classes will be registered automatically. In other cases the COM classes need to be registered manualy. When you distribute your app. the COM classes must be registered too on the user's computer.

Inno setup example:

[Files]
Source: "C:\Tags Library\Setup files\Bin\Win32\TagsLibraryCOM.dll"; DestDir: "{app}\Bin\Win32"; Flags: regserver 32bit
Source: "C:\Tags Library\Setup files\Bin\Win64\TagsLibraryCOM.dll"; DestDir: "{app}\Bin\Win64"; Flags: regserver 64bit; Check: IsWin64

Manual registration: Run an elevated command prompt, change dir into the folder where 'TagsLibraryCOM.dll' is located, run the following: "regsvr32 TagsLibraryCOM.dll". This should register the COM class. Do this for the desired Win32 and/or Win64 version.
'TagsLib.dll' (and 'FreeImage.dll' if using AddCoverArtFromFile() function - on Win64 'vcomp200.dll' also) is needed on the search path, eg. beside your .exe, or copy the needed DLLs to \Windows\System32\ (Win64 DLLs on a 64 bit OS) and/or \Windows\SysWOW64\ (Win32 DLLs on a 64 bit OS) folder. If the OS is 32 bit then copy the needed DLLs to \Windows\System32\ (from the Win32 folder).
To use the library in VBScript, on a 64 bit OS, the VBScript process is 64 bit so the needed DLLs have to be from the Win64 folder, beside the .VBS file or in the System32 folder as written above.

Using the component, loading tags

TagsLibraryDefaultTagLoadPriority array holds the default values specifying the tag type preference (priority) when loading the tags (element 0 has the highest priority). These values are applied for the newly created TTags classes. So to have effect it has to be specified before creating a TTags class instance.
First create a TTags class, and then call the LoadFromFile() or the LoadFromBASS() function. If tags are found the .Loaded property is set to True.
To extract the tags you can use TTags.GetTag('TITLE') function to get the 'title' tag, returns an empty string if no such tag is present. To get more details use the TTags.Tag('TITLE') function which returns a TTag class or nil if no such tag is present. On how to iterate over the tags please see the tutorials.
To extract the cover arts, use the TTags.CoverArts[i] array, you can obtain the cover art count with TTags.CoverArtCount.
Note that the tag loading is 'joining' all the found tags by the specified preference, so if there's an ID3v1 tag with a title and there's an ID3v2 tag also with a title the title will be listed as by the ID3v2 tag's field as it has higher priority by the default TagsLibraryDefaultTagLoadPriority.
If you want to load a particular tag type directly, or access a particular tag class, you can always use the 'sub-classes', like TTags.APEv2Tag.LoadFromFile('FileName'), to read-in the tags use the TTags.LoadAPEv2Tags function after loading the tags directly.
To understand the functions and usage of these tagging 'sub-classes' please see the provided tutorials in the folders of the tagging libraries.

Saving tags

The library is designed to provide the functionality to load any tag and save to any tag format after. So you can load an ID3v2 taged file and then save this tag as a Flac or MP4 tag afterwards. As much information as possible is preserved.
To set a tag field use TTags.SetTag('TITLE', 'Song title'), the TTags.SetList() function can be used to set the 'TIPL' (involved people) and 'TMCL' (musician credits) tags.
The tags can be saved automatically (default behaviour) with TTags.SaveToFile('FileName.mp3'), or explicitly specifying the tag format to be written with TTags.SaveToFile('FileName.mp3', ttID3v2) for example.

Basic steps for using the .dll version

1. Load the library by calling 'InitTagsLibrary'
2. Create a tags object by calling 'TagsLibrary_Create', will return the object handle to be used in the next steps
3. Call 'TagsLibrary_Load' use 'ttAutomatic' for 'TagType' and use 'True' for 'ParseTags'
4. Get tag with the function 'TagsLibrary_GetTag'/ set tag with 'TagsLibrary_SetTag'
5. To save the tag use 'TagsLibrary_Save'
6. To free the resources used by the object call 'TagsLibrary_Free'
7. When exiting the application call 'FreeTagsLibrary'

Note: When using 'TagsLib.dll' no other .dlls are needed, but when using the functions TagsLibrary_GetCoverArtBitmapHandle() and/or TagsLibrary_AddCoverArtFromFileAutomatic() 'FreeImage.dll' must be available on the .dll load path (eg. beside the .exe). On Win64 'vcomp200.dll' is also needed. 'FreeImage.dll' is loaded dynamicaly on first call to these functions, if you don't call them 'FreeImage.dll' will not be loaded at all, so it's not needed then at all.

Overview of the .dll functions

TagsLibrary_Create: HTags;

Create a tag library object.
Return value is a handle to the object.
TagsLibrary_Free(Tags: HTags): LongBool;

Free the object created with 'TagsLibrary_Create'.
Note: there's no clear function for the object, always re-create the tags library object if you want to clear it.
TagsLibrary_Load(Tags: HTags; FileName: PWideChar; TagType: TTagType; ParseTags: LongBool): Integer;

Loads the tags from the specified 'FileName'. When 'TagType' is 'ttAutomatic' all the supported tag types are loaded (in the order specified by 'TagsLibrary_SetTagLoadPriority'), to load a particular tag type, specify 'TagType' to something other then 'ttAutomatic'.
To check if tags are found use the function 'TagsLibrary_Loaded'.
'ParseTags' should be always 'True', but if you want to load a particular tag type then this flag specifies wheather to parse the tags to be used by 'ttAutomatic'. In other words, set 'ParseTags' to 'False' if you will use for example 'ttID3v2' in all function calls (so then there's no need to parset the tags).
Return value is an error code, '0' means success.
TagsLibrary_LoadFromBASS(Tags: HTags; Channel: Cardinal): Integer;

Load the tags from a BASS channel handle. Useful for URL (internet) streams. But can be used for local (file) streams also.
Return value is an error code, '0' means success.
TagsLibrary_Save(Tags: HTags; FileName: PWideChar; TagType: TTagType): Integer;

Save the tags to file specified by 'FileName'. Using 'TagType' 'ttAutomatic' will decide the format by the following:
- If the 'FileName' is the same as the one used for loading, the tags will be saved in all formats which were present in the source file.
- If the 'FileName' is different, format will be decided by the file extension.
To save a particular tag type specify it with 'TagType' as eg. 'ttID3v2'.
Return value is an error code, '0' means success.
TagsLibrary_SaveEx(Tags: HTags; FileName: PWideChar; TagType: TTagType): Integer;

Save the tags without conversion ('ParseTag' and tags set with 'ttAutomatic' option will not have effect). Useful if you want to work with a particular tag type.
Return value is an error code, '0' means success.
TagsLibrary_RemoveTag(FileName: PWideChar; TagType: TTagType): Integer;

Remove all tags from 'FileName', to delete a particular tags type set it with 'TagType'.
Return value is an error code, '0' means success.
TagsLibrary_GetTag(Tags: HTags; Name: PWideChar; TagType: TTagType): PWideChar;

Get a pointer to a unicode (wide) string tag specified by 'Name' (for example 'TITLE').
Return value is pointing to an empty string if no such tag found.
TagsLibrary_Loaded(Tags: HTags; TagType: TTagType): LongBool;

Test if tags are loaded. If 'TagType' is 'ttAutomatic' then the return value is 'False' if no tag exists in the file at all, 'True' otherwise.
TagsLibrary_GetTagEx(Tags: HTags; Name: PWideChar; TagType: TTagType; var ExtTag: TExtTag): LongBool;

Get extended (detailed) information about a tag. Useful for 'ttID3v2' TXXX, WXXX, COMM frames.
Return value is 'False' if no tag specified by 'Name' (eg. 'TITLE') is present in the tags.
TagsLibrary_GetTagByIndexEx(Tags: HTags; Index: Integer; TagType: TTagType; var ExtTag: TExtTag): LongBool;

Same as 'TagsLibrary_GetTagEx' just get the tag details by index. To iterate over all the tags use the 'TagsLibrary_TagCount' function and this function in a for loop.
Return value is 'False' if 'Index' is invalid.
TagsLibrary_SetTag(Tags: HTags; Name: PWideChar; Value: PWideChar; TagType: TTagType): LongBool;

Simply set a tag specified by 'Name' to value specified by 'Value'. If there's already a field with the specified name it will be replaced with the new value.
When using with a particular tag type, eg. 'ttID3v2', 'Name' specifies an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example '�ART' (artist).
Return value is 'True' on success.
TagsLibrary_SetTagEx(Tags: HTags; TagType: TTagType; ExtTag: TExtTag): LongBool;

Set a tag with extended (detailed) attributes. 'ExtTag.Name' specifies the tag's name, an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example '�ART' (artist).
ExtTag.ValueSize specifies ExtTag.Value length in bytes.
For using it in 'ttAutomatic' mode, use 'ExtTag.Name' as 'TITLE'.
This function is mostly useful for 'ttID3v2' WXXX and TXXX frames.
Return value is 'True' on success.
TagsLibrary_AddTag(Tags: HTags; Name: PWideChar; Value: PWideChar; TagType: TTagType): Integer;

Add a tag specified by 'Name' to value specified by 'Value'. If there's already a field with the specified name a new one will added, and the previous is preserved.
When using with a particular tag type, eg. 'ttID3v2', 'Name' specifies an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example '�ART' (artist).
But be carefull because eg. MP4 tags canot contain multiple atoms of the same type.
Return value is 'True' on success.
TagsLibrary_AddTagEx(Tags: HTags; TagType: TTagType; ExtTag: TExtTag): Integer;

Add a tag with extended (detailed) attributes. 'ExtTag.Name' specifies the tag's name, an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example '�ART' (artist).
ExtTag.ValueSize specifies ExtTag.Value length in bytes.
For using it in 'ttAutomatic' mode, use 'ExtTag.Name' as 'TITLE'.
This function is mostly useful for 'ttID3v2' WXXX and TXXX frames.
Return value is 'True' on success.
TagsLibrary_TagCount(Tags: HTags; TagType: TTagType): Integer;

Retrieve the tag count for the specified 'TagType' tag type.
Note that for example for ID3v2 tags the cover art is also a tag (frame) so will be included in the return value.
TagsLibrary_CoverArtCount(Tags: HTags; TagType: TTagType): Integer;

Retrieve the cover art count for the 'TagType'.
TagsLibrary_GetCoverArt(Tags: HTags; TagType: TTagType; Index: Integer; var CoverArt: TCoverArtData): LongBool;

Extract the cover art specified by 'Index' into the 'CoverArt' structure.
'CoverArt.Data' points to the cover art data bytes, 'CoverArt.DataSize' specifies the data size. You can use 'CoverArt.MIMEType' or 'CoverArt.PictureFormat' to identify the cover art picture format.
Return value is 'True' on success.
TagsLibrary_DeleteCoverArt(Tags: HTags; TagType: TTagType; Index: Integer): LongBool;

Delete a cover art specified by 'Index'. Use 'TagsLibrary_CoverArtCount' to check how many cover arts are in the tag.
Return value is 'True' on success.
TagsLibrary_SetCoverArt(Tags: HTags; TagType: TTagType; Index: Integer; var CoverArt: TCoverArtData): LongBool;

Set cover art specified by 'Index'.
Try to fill in all the attributes in 'CoverArt', although not all are needed for all the tag types.
Return value is 'True' on success.
TagsLibrary_AddCoverArt(Tags: HTags; TagType: TTagType; var CoverArt: TCoverArtData): Integer;

Add a new cover art.
Try to fill in all the attributes in 'CoverArt', although not all are needed for all the tag types.
Return value is 'True' on success.
TagsLibrary_AddCoverArtFromFile(Tags: HTags; TagType: TTagType; FileName: PChar; var CoverArt: TCoverArtData): LongBool;

Add a cover art from file specified by 'FileName'.
Try to fill in all the attributes in 'CoverArt', although not all are needed for all the tag types.
Return value is 'True' on success.
function TagsLibrary_GetCoverArtBitmapHandle(Tags: TTags; TagType: TTagType; Index: Integer; var CoverArt: TCoverArtData; var BitmapHandle: THandle; Width: Integer; Height: Integer; KeepAspectRatio: LongBool; Resampler: Integer; Handle: THandle): LongBool;

Get the cover art's HBITMAP handle specified by 'Index' using Free Image Library with optional high quality resize. All picture formats supported by Free Image Library are supported.
The cover art details are returned in 'CoverArt'.
The HBITMAP handle is returned in 'BitmapHandle'. In Delphi if you assign this handle to a 'TBitmap.Handle' Delphi will automatically free this handle, in other cases call 'DelecteObject(BitmapHandle)' after the bitmap is not needed.
'Width' and 'Height' are opional, use '0' to retrieve the picture in it's original size.
Set 'KeepAspectRatio' to True to resize the picture based on max. 'Width' or 'Height'.
'Resampler' is used to specify a Free Image Library resampler to be used for resizing the picture, Lanczos3 is recommended for sharpest result.
'Handle' specifies a Handle to be used for GetDC() when creating the DIB (use your windows' HWND here).
Return value is 'True' on success. Return value is also 'False' if 'FreeImage.dll' could not be loaded.
This function is only available on Windows, 'FreeImage.dll' must be available on the .dll load path (eg. beside the .exe). On Win64 'vcomp200.dll' is also needed. 'FreeImage.dll' is loaded dynamicaly on first call to this function, if you don't call this function 'FreeImage.dll' will not be loaded at all, so it's not needed then.
function TagsLibrary_AddCoverArtFromFileAutomatic(Tags: TTags; TagType: TTagType; FileName: PChar; Name: PChar; Description: PChar; CoverType: Integer; Handle: THandle): Integer;
Add a cover art specified by 'FileName' using Free Image Library. Picture formats supported: JPEG, PNG, GIF, BMP and TIFF. If the picture's format is not the previously mentioned one but it's supported by Free Image Library MIME Type will be set as 'image/' + file's extension.
'Name' is only used with APEv2, should be 'Cover Art (Front)'.
'Description' is for description about the picture, used for ID3v2.
'CoverType': ID3v2 cover type, use '3' as front cover.
'Handle' specifies a Handle to be used for GetDC() when creating the DIB (use your windows' HWND here).
Return value is the new cover art index on success, '- 1' on fail. Return value is also '- 1' if 'FreeImage.dll' could not be loaded.
This function is only available on Windows, 'FreeImage.dll' must be available on the .dll load path (eg. beside the .exe). On Win64 'vcomp200.dll' is also needed. 'FreeImage.dll' is loaded dynamicaly on first call to this function, if you don't call this function 'FreeImage.dll' will not be loaded at all, so it's not needed then.
TagsLibrary_SetTagLoadPriority(Tags: HTags; TagPriorities: TTagPriority): LongBool;

Set the tag loading priority array. The value in 'TagPriorities[0]' has the highest priority.
Use 'Tags' = 'nil' or 'null' to set the global tag load priority. All tag library classes created after calling this function will use these settings.
Return value should be always 'True'.
TagsLibrary_GetTagData(Tags: HTags; Index: Integer; TagType: TTagType; var TagData: TTagData): LongBool;

Get binary data of a tag frame. Useful for ID3v2 GEOB, etc. binary frames and MP4 binary atoms.
When using 'TagType' = 'ttMP4', 'TagData.DataType' is for example:
- 0: binary
- 1: text
- 13: cover art
- 14: cover art
- 21: binary
Return value is 'True' on success.
TagsLibrary_SetTagData(Tags: HTags; Index: Integer; TagType: TTagType; TagData: TTagData): LongBool;

Set binary data of a tag frame. Useful for ID3v2 GEOB, APEv2 binary frames, etc. and MP4 tags.
When using 'TagType' = 'ttMP4', 'TagData.DataType' is needed for example:
- 0: binary
- 1: text
- 13: cover art
- 14: cover art
- 21: binary
Return value is 'True' on success.
TagsLibrary_GetCARTPostTimer(Tags: HTags; Index: Integer; var PostTimer: TCARTPostTimer): LongBool;

Get WAV CART post timer specified by 'Index'. There are 8 CART post timers, Index range is 0 to 7.
Result is 'False' if 'Index' is out of bounds.
TagsLibrary_SetCARTPostTimer(Tags: HTags; Index: Integer; PostTimer: TCARTPostTimer): LongBool;

Set WAV CART post timer specified by 'Index'. There are 8 CART post timers, Index range is 0 to 7.
Result is 'False' if 'Index' is out of bounds.
TagsLibrary_ClearCARTPostTimer(Tags: HTags; Index: Integer): LongBool;

Clear WAV CART post timer specified by 'Index'. There are 8 CART post timers, Index range is 0 to 7.
Result is 'False' if 'Index' is out of bounds.
TagsLibrary_GetConfig(Tags: HTags; var Value: NativeUInt; Option: Integer; TagType: TTagType): LongBool;
TagsLibrary_SetConfig(Tags: HTags; Value: NativeUInt; Option: Integer; TagType: TTagType): LongBool;

Get and set configuration settings. If 'Tags' = nil then means global parameters.
'Option' can be:
- TAGSLIBRARY_PADDING_SIZE_TO_WRITE: set padding size to write when saving the tags. When set as global, setting will affect all newly created Tags objects.
- TAGSLIBRARY_PARSE_OGG_PLAYTIME: set getting of Ogg Vorbis and Opus audio file's play time. Setting to 'True' results longer loading time. Default is 'True'. When set as global, setting will affect all newly created Tags objects.
- TAGSLIBRARY_PARSE_ID3v2_AUDIO_ATTRIBUTES: set getting of MPEG, WAV, AIFF/AIFC, DSD .dsf audio file's attributes. Setting to 'False' results quicker loading. Default is 'True'. When set as global, setting will affect all newly created Tags objects.
- TAGSLIBRARY_MP4TAG_KEEP_PADDING: set to preserve padding (add as much as needed to fit the new tag) or always write 'TAGSLIBRARY_PADDING_SIZE_TO_WRITE' value padding.
- TAGSLIBRARY_PARSE_WAVPACK_AUDIO_ATTRIBUTES: set getting of WavPack audio file's attributes. Setting to 'False' results quicker loading. Default is 'False'. When set as global, setting will affect all newly created Tags objects.
- TAGSLIBRARY_PARSE_MUSEPACK_AUDIO_ATTRIBUTES: set getting of MusePack audio file's attributes. Setting to 'False' results quicker loading. Default is 'False'. When set as global, setting will affect all newly created Tags objects.
- TAGSLIBRARY_DEEP_OPUS_BITRATE_SCAN: set deep scanning of Opus audio files and get true w/o overhead bit rate. Results slower loading of Opus audio files, default is 'False'.
- TAGSLIBRARY_PARSE_COVER_ARTS: use this option to disable cover art loading, useful when scanning a lot of files and only the tags are needed. DO NOT SAVE THE TAGS WHEN IT'S OFF! Default is 'True'.
- TAGSLIBRARY_PARSE_AUDIO_ATTRIBUTES: use this option to disable parsing of audio attributes, useful when scanning a lot of files and onlt the tags are needed. Speeds up espeacially MP3 loading. Default is 'True'.
- TAGSLIBRARY_ID3v1_RETURN_ANSI_TEXT: useful for parsing for example russian ANSI tags. Default is 'False'.
- TAGSLIBRARY_ID3v2_RETURN_ANSI_TEXT: useful for parsing for example russian ANSI tags. This option is always global. Default is 'False'.
- TAGSLIBRARY_DEEP_VORBIS_BITRATE_SCAN: set deep scanning of Ogg Vorbis audio files and get true w/o overhead bit rate. Results slower loading of Ogg Vorbis audio files, default is 'False'.
- TAGSLIBRARY_ID3v2_APIC_TEXT_ENCODING: 0 = unicode, 1 = UTF8, 2 = ANSI.
- TAGSLIBRARY_ID3v2_WRITE_UTF8_TEXT: set to 'True' to set ID3v2 tag strings in UTF-8 form. Only newly set tags are affected, tags that are not changed have their format as read from the file. Default is UTF-16LE, 'False'.
- TAGSLIBRARY_PRESERVE_FILE_DATETIME: restore the file's "changed" date time after saving the tags, is off by default.
- TAGSLIBRARY_ID3v2_WRITE_VERSION: supported values are '0' for as source (default), '3' for ID3v2.3 and '4' for ID3v2.4.
TagsLibrary_GetVendor(Tags: HTags; TagType: TTagType): PWideChar;
TagsLibrary_SetVendor(Tags: HTags; Vendor: PWideChar; TagType: TTagType): LongBool;

Get and set vendor string. Applies to Ogg Vorbis, Opus and Flac.
Return value is nil/False otherwise.
Use with ttID3v2 to get the ID3v2 tag version.
TagsLibrary_GetAudioAttributes(Tags: HTags; AudioType: TAudioType; Attributes: Pointer): Pointer;

Get source audio file's attributes.
Supported 'AudioTypes's:
- atAutomatic: returns 'TAudioAttributes' structure (automatic source detection) in 'Attributes'
- atFlac: returns a 'TFlacAudioAttributes' structure (Flac and Ogg Flac) in 'Attributes'
- atMPEG: returns a 'TMPEGAudioAttributes' structure (.mp3, .mp2, .mp1, .mpa) in 'Attributes'
- atDSDDSF: returns a 'TDSFAudioAttributes' structure (DSD .dsf) in 'Attributes'
- atOpus: returns a 'TOpusAudioAttributes' structure (Opus) in 'Attributes'
- atVorbis: returns a 'TVorbisAudioAttributes' structure (Vorbis) in 'Attributes'
- atWAV: returns a 'TWAVEAudioAttributes' structure (WAV and RF64) in 'Attributes'
- atAIFF: returns a 'TAIFFAudioAttributes' structure (AIFF and AIFC) in 'Attributes'
- atWMA: returns a 'TWMAAudioAttributes' structure (WMA) in 'Attributes'
TagsLibrary_GetTagSize(Tags: HTags; TagType: TTagType): DWord;
Get size of the specified tag.
if TagType = ttAutomatic then retrieve sum size of all tags present in the file.
TagsLibrary_GetAudioFormat(FileName: PChar): TAudioFileFormat;
Determine audio file format of the specified file name.
TagsLibrary_GetAudioFormatMemory(MemoryAddress: Pointer; Size: UInt64): TAudioFileFormat;
Determine audio file format of the specified "memory" file.
TagsLibrary_FixWAVEFile(FileName: PChar): Integer;
Fix corrupted WAV data size value in WAV files if file is truncated for example.
TagsLibrary_GetWAVEVNT(Tags: HTags; Index: Integer; var SPEVENT: TSPEVENT): Integer;
Get WAV EVNT chunk data specified by 'Index'. Repeat the functon call until return value is 'TAGSLIBRARY_ERROR';
Note: if 'SPEVENT.TOKENDATA' is not nil you have to free it with 'VirtualFree()'.
Note: if 'SPEVENT.BOOKMARK' is not nil you have to free it with 'VirtualFree()'.
TagsLibrary_GetChapter(Tags: HTags; TagType: TTagType; FrameIndex: Integer; ChapterIndex: Integer; var Chapter: TTLChapter): Integer;
Get ID3v2 chapter ID no. 'ChapterIndex' from a 'CTOC' frame specified by 'FrameIndex'.
Error is returned if 'ChapterIndex' is not found, so call this function multiple times until error is returned to get all chapter IDs.
Only available with 'TagType = ttID3v2'.
TagsLibrary_FindChapterElementID(Tags: HTags; TagType: TTagType; ChapterElementID: PChar; var ChapterElement: TTLChapterElement): Integer;
Search for the 'ChapterElementID' that was returned with the function above, the ID3v2 frame index of the 'CHAP' frame (and it's conent) is returned in 'ChapterElement'.
Use the returnd 'ChapterElement.Index' with TagsLibrary_SetFramesContext() (se below) to switch the context to the 'CHAP' frame, so all GetTag/SetTag/Cover art functions will operate on the sub-frames of the 'ChapterElement.Index'.
Only available with 'TagType = ttID3v2'.
TagsLibrary_SetFramesContext(Tags: HTags; TagType: TTagType; FrameIndex: Integer): Integer;
Switch the context to the 'FrameIndex' frame, so all GetTag/SetTag/Cover art functions will operate on the sub-frames of the 'Index'.
Only successfull if the 'FrameIndex' is a 'CTOC' or 'CHAP' frame.
Use 'FrameIndex = - 1' to switch the context (back) to the ID3v2 root level.
Only available with 'TagType = ttID3v2'.
TagsLibrary_AddChapter(Tags: HTags; TagType: TTagType; FrameIndex: Integer; var Chapter: TTLChapter): Integer;
Add a new chapter item to a 'CTOC' frame, 'FrameIndex' is the index of the 'CTOC' frame.
Only available with 'TagType = ttID3v2'.
TagsLibrary_DeleteChapter(Tags: HTags; TagType: TTagType; FrameIndex: Integer; var Chapter: TTLChapter): Integer;
Delete chapter item in the 'CTOC' frame, 'FrameIndex' is the index of the 'CTOC' frame.
Only available with 'TagType = ttID3v2'.
TagsLibrary_SetChapterElementID(Tags: HTags; TagType: TTagType; FrameIndex: Integer; var ChapterElement: TTLChapterElement): Integer;
Set the chapter item data. 'FrameIndex' should be the index of the 'CHAP' frame.
Only available with 'TagType = ttID3v2'.
TagsLibrary_SetChapterFrameBits(Tags: HTags; TagType: TTagType; FrameIndex: Integer; TopLevelBit: LongBool; OrderedBit: LongBool): Integer;
Set the ID3v2 'CTOC' frame's flag bits.
Only 1 'CTOC' frame is allowed to have the 'TopLevelBit' set.
Only available with 'TagType = ttID3v2'.
TagsLibrary_GetChapterFrameBits(Tags: HTags; TagType: TTagType; FrameIndex: Integer; var TopLevelBit: LongBool; var OrderedBit: LongBool): Integer;
Get the ID3v2 'CTOC' frame's flag bits.
Only available with 'TagType = ttID3v2'.
TagsLibrary_FindFrame(Tags: HTags; TagType: TTagType; FrameName: PChar): Integer;
Find the frame or atom by ID 'FrameName'. The first occurence is returned, or '-1' if not found.
To find multiple frames/atoms iterate over all the frames/atoms with eg. TagsLibrary_TagCount() + TagsLibrary_GetTagByIndexEx().

WAV BEXT and CART tags (.dll version)

To set BEXT and CART tags use the 'TagsLibrary_SetTag()' function with TagType = ttWAV, available 'Name' fields:

'BEXT Description'
'BEXT Originator'
'BEXT OriginatorReference'
'BEXT OriginationDate'
'BEXT OriginationTime'
'BEXT TimeReference'
'BEXT Version'
'BEXT UMID'
'BEXT CodingHistory'
'CART Version'
'CART Title'
'CART Artist'
'CART CutID'
'CART ClientID'
'CART Category'
'CART Classification'
'CART OutCue'
'CART StartDate'
'CART StartTime'
'CART EndDate'
'CART EndTime'
'CART ProducerAppID'
'CART ProducerAppVersion'
'CART UserDef'
'CART LevelReference'
'CART PostTimer' - use as 'CART PostTimer0' through 'CART PostTimer7' with two values (for example 'MRK1 222') separated by a space character.
'CART URL'
'CART Reserved'
'CART TagText'

VBScript example

After the COM class has been registered (see above 'Installation') it can be utilised as:

    option explicit
    dim myobject
    dim atag
    set myobject = createobject("TagsLibrary.TagManager")
    myobject.LoadFromFile "C:\My test audio file.mp3", 1
    myobject.GetTagByName "TITLE", atag, 1
    Wscript.Echo atag
    set myobject=nothing

This will display the title of the specified audio file.
For all the COM class methods please see the 'TagsLibrary.ridl' or 'TagsLibrary_TLB.pas' file.

'TagType' can be one of the following (in the example above '1' is used = 'ttAutomatic'):

typedef enum
{
  ttNone       = 0,
  ttAutomatic  = 1,
  ttAPEv2      = 2,
  ttFlac       = 3,
  ttID3v1      = 4,
  ttID3v2      = 5,
  ttMP4        = 6,
  ttOpusVorbis = 7,
  ttWAV        = 8,
  ttWMA        = 9,
  ttMP4Xtra    = 10,
  ttLyrics2    = 11
} TTagType;

Notes for custom MP4 tags

To add custom MP4 tags, use '----' as atom name, and set 'name' value to your ID, like 'CUST' and standard 'mean' value is 'com.apple.iTunes'.

Notes for the .dll version

All pointers to tag data are valid only until changing the tag (setting the particular value, or loading new data), or as long as the tags library class is valid, so copy the returned strings if you need them afterwards.

Notes for WMA support

As WMA is supported through WMVCORE.DLL which is part of Windows, WMA reading/writing is only supported on the Windows platform.

Credits

C++ Builder tutorial by Robert Jackson (hsialinboy@yahoo.com)
.NET wrapper .dll and C#, VB.NET tutorial by EWeiss (http://www.un4seen.com/)

Useful information

Links

[Top]